<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 27.3.1</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="27.3.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="27.3.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P4">Part IV. The C API</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#27">Chapter 27. Techniques for Writing C Functions</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h3>27.3.1 &ndash; The Registry</h3>

<p>The registry is always located at a <em>pseudo-index</em>,
whose value is defined by <code>LUA_REGISTRYINDEX</code>.
A pseudo-index is like an index into the stack,
except that its associated value is not in the stack.
Most functions in the Lua API that accept indices as arguments
also accept pseudo-indices---the exceptions
being those functions that manipulate the stack itself,
such as <code>lua_remove</code> and <code>lua_insert</code>.
For instance, to get a value stored with key <code>"Key"</code> in the registry,
you can use the following code:
<pre>
    lua_pushstring(L, "Key");
    lua_gettable(L, LUA_REGISTRYINDEX);
</pre>

<p>The registry is a regular Lua table.
As such, you can index it with any Lua value but <B>nil</B>.
However, because all C libraries share the same registry,
you must choose with care what values you use as keys,
to avoid collisions.
A bulletproof method is to use as key the address of a static
variable in your code:
The C link editor ensures that this key
is unique among all libraries.
To use this option,
you need the function <code>lua_pushlightuserdata</code>,
which pushes on the Lua stack a value representing a C pointer.
The following code shows how to store and retrieve a number from
the registry using this method:
<pre>
    /* variable with an unique address */
    static const char Key = 'k';
    
    /* store a number */
    lua_pushlightuserdata(L, (void *)&amp;Key);  /* push address */
    lua_pushnumber(L, myNumber);  /* push value */
    /* registry[&amp;Key] = myNumber */
    lua_settable(L, LUA_REGISTRYINDEX);
    
    /* retrieve a number */
    lua_pushlightuserdata(L, (void *)&amp;Key);  /* push address */
    lua_gettable(L, LUA_REGISTRYINDEX);  /* retrieve value */
    myNumber = lua_tonumber(L, -1);  /* convert to number */
</pre>
We will discuss light userdata in more
detail in <a href="28.5.html#lightudata">Section 28.5</a>.

<p>Of course, you can also use strings as keys into the registry,
as long as you choose unique names.
String keys are particularly useful when you want to allow
other independent libraries to access your data,
because all they need to know is the key name.
For such keys, there is no bulletproof method of choosing names,
but there are some good practices,
such as avoiding common names
and prefixing your names with the library name or something like it.
Prefixes like <code>lua</code> or <code>lualib</code> are not good choices.
Another option is to use a <em>universal unique identifier</em>
(<code>uuid</code>),
as most systems now have programs to generate such identifiers
(e.g., <code>uuidgen</code> in Linux).
An <code>uuid</code> is a 128-bit number
(written in hexadecimal to form a string) that is generated by
a combination of the host IP address, a time stamp,
and a random component,
so that it is assuredly different from any other <code>uuid</code>.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="27.3.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

